From cb38c11c8496b509895e1ff9bcce5b5f42b07bb6 Mon Sep 17 00:00:00 2001 From: Yuri Astrakhan Date: Sun, 20 May 2007 23:31:44 +0000 Subject: [PATCH] API: documentation and cleanup. --- api.php | 2 +- includes/api/ApiBase.php | 11 +++++++++-- includes/api/ApiFeedWatchlist.php | 2 +- includes/api/ApiFormatBase.php | 2 +- includes/api/ApiFormatJson.php | 2 +- includes/api/ApiFormatPhp.php | 2 +- includes/api/ApiFormatWddx.php | 2 +- includes/api/ApiFormatXml.php | 2 +- includes/api/ApiFormatYaml.php | 2 +- includes/api/ApiHelp.php | 4 +++- includes/api/ApiLogin.php | 2 +- includes/api/ApiMain.php | 4 ++-- includes/api/ApiOpenSearch.php | 2 +- includes/api/ApiPageSet.php | 11 ++++++++++- includes/api/ApiQuery.php | 10 +++++++++- includes/api/ApiQueryAllpages.php | 4 +++- includes/api/ApiQueryBacklinks.php | 7 ++++++- includes/api/ApiQueryBase.php | 5 ++++- includes/api/ApiQueryCategories.php | 4 +++- includes/api/ApiQueryExternalLinks.php | 4 +++- includes/api/ApiQueryImages.php | 6 ++++-- includes/api/ApiQueryInfo.php | 4 +++- includes/api/ApiQueryLangLinks.php | 4 +++- includes/api/ApiQueryLinks.php | 4 +++- includes/api/ApiQueryLogEvents.php | 4 +++- includes/api/ApiQueryRecentChanges.php | 5 ++++- includes/api/ApiQueryRevisions.php | 6 +++++- includes/api/ApiQuerySiteinfo.php | 4 +++- includes/api/ApiQueryWatchlist.php | 5 ++++- includes/api/ApiResult.php | 2 +- 30 files changed, 95 insertions(+), 33 deletions(-) diff --git a/api.php b/api.php index d3274dc4cf..28c1ef37f6 100644 --- a/api.php +++ b/api.php @@ -4,7 +4,7 @@ /** * API for MediaWiki 1.8+ * -* Copyright (C) 2006 Yuri Astrakhan +* Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index 5ca43c3924..248b6007b1 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -200,7 +200,14 @@ abstract class ApiBase { $prompt = 'One value: '; if (is_array($type)) { - $desc .= $paramPrefix . $prompt . implode(', ', $type); + $choices = array(); + $nothingPrompt = false; + foreach ($type as $t) + if ($t=='') + $nothingPrompt = 'Can be empty, or '; + else + $choices[] = $t; + $desc .= $paramPrefix . $nothingPrompt . $prompt . implode(', ', $choices); } else { switch ($type) { case 'namespace': diff --git a/includes/api/ApiFeedWatchlist.php b/includes/api/ApiFeedWatchlist.php index b989ab0525..6b435e1bea 100644 --- a/includes/api/ApiFeedWatchlist.php +++ b/includes/api/ApiFeedWatchlist.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiFormatBase.php b/includes/api/ApiFormatBase.php index ae3d8f34fb..f1fbc0e0ab 100644 --- a/includes/api/ApiFormatBase.php +++ b/includes/api/ApiFormatBase.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiFormatJson.php b/includes/api/ApiFormatJson.php index 8184c8c74b..16a23755d9 100644 --- a/includes/api/ApiFormatJson.php +++ b/includes/api/ApiFormatJson.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiFormatPhp.php b/includes/api/ApiFormatPhp.php index 20480b6df4..07eea096a1 100644 --- a/includes/api/ApiFormatPhp.php +++ b/includes/api/ApiFormatPhp.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiFormatWddx.php b/includes/api/ApiFormatWddx.php index ad902b630c..7de8f0153d 100644 --- a/includes/api/ApiFormatWddx.php +++ b/includes/api/ApiFormatWddx.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiFormatXml.php b/includes/api/ApiFormatXml.php index 0c81c2fc9c..3a7cf42df4 100644 --- a/includes/api/ApiFormatXml.php +++ b/includes/api/ApiFormatXml.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiFormatYaml.php b/includes/api/ApiFormatYaml.php index 5fc89b9a40..e67ee62199 100644 --- a/includes/api/ApiFormatYaml.php +++ b/includes/api/ApiFormatYaml.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiHelp.php b/includes/api/ApiHelp.php index 570c7874d4..0d23681b3f 100644 --- a/includes/api/ApiHelp.php +++ b/includes/api/ApiHelp.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * This is a simple class to handle action=help + * * @addtogroup API */ class ApiHelp extends ApiBase { diff --git a/includes/api/ApiLogin.php b/includes/api/ApiLogin.php index 9a8c70ee18..f5cf4042e8 100644 --- a/includes/api/ApiLogin.php +++ b/includes/api/ApiLogin.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php index 62140dfbcb..2f2e34fc06 100644 --- a/includes/api/ApiMain.php +++ b/includes/api/ApiMain.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -327,7 +327,7 @@ class ApiMain extends ApiBase { */ protected function getCredits() { return array( - 'This API is being implemented by Yuri Astrakhan [[User:Yurik]] / @gmail.com', + 'This API is being implemented by Yuri Astrakhan [[User:Yurik]] / @gmail.com', 'Please leave your comments and suggestions at http://www.mediawiki.org/wiki/API' ); } diff --git a/includes/api/ApiOpenSearch.php b/includes/api/ApiOpenSearch.php index 48d6b1373c..4b06142731 100644 --- a/includes/api/ApiOpenSearch.php +++ b/includes/api/ApiOpenSearch.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by diff --git a/includes/api/ApiPageSet.php b/includes/api/ApiPageSet.php index d2f561040a..de1d2de8dd 100644 --- a/includes/api/ApiPageSet.php +++ b/includes/api/ApiPageSet.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,15 @@ if (!defined('MEDIAWIKI')) { } /** + * This class contains a list of pages that the client has requested. + * Initially, when the client passes in titles=, pageids=, or revisions= parameter, + * an instance of the ApiPageSet class will normalize titles, + * determine if the pages/revisions exist, and prefetch any additional data page data requested. + * + * When generator is used, the result of the generator will become the input for the + * second instance of this class, and all subsequent actions will go use the second instance + * for all their work. + * * @addtogroup API */ class ApiPageSet extends ApiQueryBase { diff --git a/includes/api/ApiQuery.php b/includes/api/ApiQuery.php index 0aecc12631..b3e05672db 100644 --- a/includes/api/ApiQuery.php +++ b/includes/api/ApiQuery.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,14 @@ if (!defined('MEDIAWIKI')) { } /** + * This is the main query class. It behaves similar to ApiMain: based on the parameters given, + * it will create a list of titles to work on (an instance of the ApiPageSet object) + * instantiate and execute various property/list/meta modules, + * and assemble all resulting data into a single ApiResult object. + * + * In the generator mode, a generator will be first executed to populate a second ApiPageSet object, + * and that object will be used for all subsequent modules. + * * @addtogroup API */ class ApiQuery extends ApiBase { diff --git a/includes/api/ApiQueryAllpages.php b/includes/api/ApiQueryAllpages.php index a6ad4e89a0..e70398c041 100644 --- a/includes/api/ApiQueryAllpages.php +++ b/includes/api/ApiQueryAllpages.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * Query module to enumerate all available pages. + * * @addtogroup API */ class ApiQueryAllpages extends ApiQueryGeneratorBase { diff --git a/includes/api/ApiQueryBacklinks.php b/includes/api/ApiQueryBacklinks.php index 518041eb78..7edfa60520 100644 --- a/includes/api/ApiQueryBacklinks.php +++ b/includes/api/ApiQueryBacklinks.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,11 @@ if (!defined('MEDIAWIKI')) { } /** + * This is three-in-one module to query: + * * backlinks - links pointing to the given page, + * * embeddedin - what pages transclude the given page within themselves, + * * imageusage - what pages use the given image + * * @addtogroup API */ class ApiQueryBacklinks extends ApiQueryGeneratorBase { diff --git a/includes/api/ApiQueryBase.php b/includes/api/ApiQueryBase.php index 523c41e65c..06f6612473 100644 --- a/includes/api/ApiQueryBase.php +++ b/includes/api/ApiQueryBase.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,9 @@ if (!defined('MEDIAWIKI')) { } /** + * This is a base class for all Query modules. + * It provides some common functionality such as constructing various SQL queries. + * * @addtogroup API */ abstract class ApiQueryBase extends ApiBase { diff --git a/includes/api/ApiQueryCategories.php b/includes/api/ApiQueryCategories.php index f27de7e30c..4b1acd41ad 100644 --- a/includes/api/ApiQueryCategories.php +++ b/includes/api/ApiQueryCategories.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * A query module to enumerate categories the set of pages belong to. + * * @addtogroup API */ class ApiQueryCategories extends ApiQueryGeneratorBase { diff --git a/includes/api/ApiQueryExternalLinks.php b/includes/api/ApiQueryExternalLinks.php index 83234bdefb..02af93d7de 100644 --- a/includes/api/ApiQueryExternalLinks.php +++ b/includes/api/ApiQueryExternalLinks.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * A query module to list all external URLs found on a given set of pages. + * * @addtogroup API */ class ApiQueryExternalLinks extends ApiQueryBase { diff --git a/includes/api/ApiQueryImages.php b/includes/api/ApiQueryImages.php index b2aef25cf0..558e512fe7 100644 --- a/includes/api/ApiQueryImages.php +++ b/includes/api/ApiQueryImages.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * This query adds subelement to all pages with the list of images embedded into those pages. + * * @addtogroup API */ class ApiQueryImages extends ApiQueryGeneratorBase { @@ -109,7 +111,7 @@ class ApiQueryImages extends ApiQueryGeneratorBase { } protected function getDescription() { - return 'Returns all links from the given page(s)'; + return 'Returns all images contained on the given page(s)'; } protected function getExamples() { diff --git a/includes/api/ApiQueryInfo.php b/includes/api/ApiQueryInfo.php index 26032262c5..4d95da8afe 100644 --- a/includes/api/ApiQueryInfo.php +++ b/includes/api/ApiQueryInfo.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * A query module to show basic page information. + * * @addtogroup API */ class ApiQueryInfo extends ApiQueryBase { diff --git a/includes/api/ApiQueryLangLinks.php b/includes/api/ApiQueryLangLinks.php index 073b53ec0f..62c0fed48c 100644 --- a/includes/api/ApiQueryLangLinks.php +++ b/includes/api/ApiQueryLangLinks.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * A query module to list all langlinks (links to correspanding foreign language pages). + * * @addtogroup API */ class ApiQueryLangLinks extends ApiQueryBase { diff --git a/includes/api/ApiQueryLinks.php b/includes/api/ApiQueryLinks.php index 9119a0f0e9..46549ca2b0 100644 --- a/includes/api/ApiQueryLinks.php +++ b/includes/api/ApiQueryLinks.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * A query module to list all wiki links on a given set of pages. + * * @addtogroup API */ class ApiQueryLinks extends ApiQueryGeneratorBase { diff --git a/includes/api/ApiQueryLogEvents.php b/includes/api/ApiQueryLogEvents.php index df30c39c39..0ae53843cb 100644 --- a/includes/api/ApiQueryLogEvents.php +++ b/includes/api/ApiQueryLogEvents.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * Query action to List the log events, with optional filtering by various parameters. + * * @addtogroup API */ class ApiQueryLogEvents extends ApiQueryBase { diff --git a/includes/api/ApiQueryRecentChanges.php b/includes/api/ApiQueryRecentChanges.php index a66788cd66..93886341f4 100644 --- a/includes/api/ApiQueryRecentChanges.php +++ b/includes/api/ApiQueryRecentChanges.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,9 @@ if (!defined('MEDIAWIKI')) { } /** + * A query action to enumerate the recent changes that were done to the wiki. + * Various filters are supported. + * * @addtogroup API */ class ApiQueryRecentChanges extends ApiQueryBase { diff --git a/includes/api/ApiQueryRevisions.php b/includes/api/ApiQueryRevisions.php index c54250969f..5f238d6134 100644 --- a/includes/api/ApiQueryRevisions.php +++ b/includes/api/ApiQueryRevisions.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,10 @@ if (!defined('MEDIAWIKI')) { } /** + * A query action to enumerate revisions of a given page, or show top revisions of multiple pages. + * Various pieces of information may be shown - flags, comments, and the actual wiki markup of the rev. + * In the enumeration mode, ranges of revisions may be requested and filtered. + * * @addtogroup API */ class ApiQueryRevisions extends ApiQueryBase { diff --git a/includes/api/ApiQuerySiteinfo.php b/includes/api/ApiQuerySiteinfo.php index f174782c16..2931535877 100644 --- a/includes/api/ApiQuerySiteinfo.php +++ b/includes/api/ApiQuerySiteinfo.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,8 @@ if (!defined('MEDIAWIKI')) { } /** + * A query action to return meta information about the wiki site. + * * @addtogroup API */ class ApiQuerySiteinfo extends ApiQueryBase { diff --git a/includes/api/ApiQueryWatchlist.php b/includes/api/ApiQueryWatchlist.php index 4ce7b6bbb4..5ffe6b0813 100644 --- a/includes/api/ApiQueryWatchlist.php +++ b/includes/api/ApiQueryWatchlist.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -29,6 +29,9 @@ if (!defined('MEDIAWIKI')) { } /** + * This query action allows clients to retrieve a list of recently modified pages + * that are part of the logged-in user's watchlist. + * * @addtogroup API */ class ApiQueryWatchlist extends ApiQueryGeneratorBase { diff --git a/includes/api/ApiResult.php b/includes/api/ApiResult.php index 82fc8e9101..d3231c9bc0 100644 --- a/includes/api/ApiResult.php +++ b/includes/api/ApiResult.php @@ -5,7 +5,7 @@ * * API for MediaWiki 1.8+ * - * Copyright (C) 2006 Yuri Astrakhan + * Copyright (C) 2006 Yuri Astrakhan @gmail.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by -- 2.20.1